ASPNETCORE_ENVIRONMENT 失效的原因

TLDR

• 當在 Windows 全域環境變數設定 ASPNETCORE_ENVIRONMENT 後，若應用程式仍讀取不到對應的 appsettings.{環境}.json，通常是因為 IIS 尚未載入最新的環境變數。
• 僅重啟網站或應用程式集區（Application Pool）無法更新 IIS 服務層級的環境變數。
• 必須執行 iisreset 指令強制重啟 IIS 服務，才能使全域環境變數生效。

環境變數設定失效的問題分析

問題情境

什麼情況下會遇到這個問題：當開發者依照微軟官方文件，在 Windows 作業系統中設定全域環境變數 ASPNETCORE_ENVIRONMENT，卻發現 ASP.NET Core 應用程式在 IIS 上執行時，仍無法正確載入對應的環境設定檔（例如 appsettings.Development.json 或 appsettings.Staging.json），而是持續讀取預設的 appsettings.json。

原因分析

ASP.NET Core 在 IIS 上執行時，環境變數的讀取與 IIS 的處理程序生命週期有關。即便透過 Windows 系統設定介面修改了全域環境變數，IIS 的背景服務程序（W3SVC）並不會自動偵測並重新載入這些變數。僅僅重啟網站或回收應用程式集區（Recycle Application Pool）屬於應用程式層級的重啟，無法強制 IIS 服務重新讀取作業系統的全域環境變數。

解決方案

若要確保全域環境變數變更生效，必須強制重啟 IIS 服務。請以系統管理員權限開啟命令提示字元或 PowerShell，並執行以下指令：

iisreset /restart

TIP

執行上述指令時，可能需要系統管理員權限。

驗證結果

執行 iisreset 後，IIS 服務會重新啟動並讀取最新的系統環境變數。此時應用程式將能正確識別 ASPNETCORE_ENVIRONMENT 的值，並載入對應的 appsettings.{環境}.json 設定檔。

---

異動歷程

1. 2024-09-19

   • 初版文件建立。